---
title: "Проект Документирования FreeBSD: SGML"
sidenav: docs
---

= Проект Документирования FreeBSD: SGML

The Documentation Project использует SGML в качестве стандартного средства для написания документации.

Сокращение SGML означает **S**tandard **G**eneralized **M**arkup **L**anguage (Стандартный Формализованный Язык Разметки).

По сути (и да простят нас SGML-пуристы, присутствующие среди аудитории, к которой мы обращаемся) SGML является языком для написания других языков.

Скорее всего, вы уже работали с SGML, не подозревая об этом. HTML, язык, на котором пишутся страницы web, имеет формальное описание. Это описание написано на SGML. Когда вы пишете в HTML, вы *не* пишете на SGML (per se), но используете язык, заданный при помощи SGML.

Существует много, очень много языков разметки, которые заданы с помощью SGML. HTML - один из них. Другой называется "DocBook". Этот язык был разработан специально для написания технической документации, и поэтому в нем имеется множество тегов (маркеры в виде `<содержимое тегов>`) для описания технической документации с последующим форматированием. Проект документирования FreeBSD адаптировал его и определил несколько новых элементов, чтобы сделать его более подходящим.

Например, вот так может выглядеть короткий параграф в HTML (не обращайте внимания на содержимое, смотрите на теги):

....
    <p>Пароли хранятся в <tt>/etc/passwd</tt>.  Чтобы отредактировать этот
      файл, вы должны использовать <b><tt>vipw</tt></b>.  Однако, если вам
      нужно только добавить в систему нового пользователя, вы можете
      воспользоваться утилитой <b><tt>adduser</tt></b>.</p>
....

Тот же параграф, оформленный в стандарте DocBook, выглядит как

....
    <para>Пароли хранятся в <filename>/etc/passwd</filename>.  Чтобы
      отредактировать этот файл, вы должны использовать
      <command>vipw</command>.  Однако, если вам нужно только добавить в
      систему нового пользователя, вы можете воспользоваться утилитой
      <command>adduser</command>.</para>
....

Как вы можете видеть, DocBook более 'выразителен', чем HTML. В примере с HTML задается вывод имени файла шрифтом 'пишущей машинки'. В примере с DocBook вывод имени файла задается именно как 'имя файла', конкретное представление имени файла не оговаривается.

Имеется несколько плюсов использования этой более выразительной формы разметки:

* В ней нет разночтений или противоречий.
+
Вам не нужно терять время, обдумывая "Хм, мне нужно вывести название файла, должен ли я использовать 'tt', 'b', или, может, 'em'?"
+
Вместо этого вы просто используете нужный тег в нужном месте.
+
Процедура преобразования из DocBook в другие форматы (HTML, Postscript(R), и так далее) отвечает за то, чтобы все элементы <filename> выглядели одинаково.
* Вы перестаёте думать о том, как будет выглядеть ваш документ, и сосредотачиваетесь на его содержимом.
* Так как документация не привязана ни к какому конкретному выходному формату, та же самая документация может быть представлена во многих различных форматах-просто текст, HTML, PostScript, RTF, PDF и так далее.
* Документация становится более 'умной', поэтому с ней могут быть выполнены более интеллектуальные операции. Например, становится возможным автоматически генерировать индекс, в котором указаны все команды, упомянутые в документе.

Они похожи на таблицы стилей Microsoft(R) Word, только гораздо более мощные.

Конечно же, эти возможности достигаются определенной ценой;

* Так как тегов, которые вы можете использовать, гораздо больше, требуется больше времени на их изучение и понимание того, как использовать их эффективно.
+
Хороший способ обучения SGML и DocBook является чтение исходных текстов множества образцовых документов и сравнение того, как разные авторы оформляют подобную информацию.
* Процесс преобразования не так уж прост.

== Что, если вы не знаете DocBook? Можете ли вы предоставлять нам документацию?

Да, можете. Однозначно. Любая документация лучше, чем ее отсутствие. Если у вас есть документация, которую вы хотите нам предоставить, и она размечена не в формате DocBook, ничего страшного.

link:../submitting/[Пошлите] нам документацию обычным образом. Кто-нибудь из Проекта рассмотрит документацию, которую вы послали, разметит ее за вас и включит в систему. С некоторой вероятностью обратно вам будет выслан размеченный текст. Это весьма полезно, так как вы сможете сравнить документацию "до и после", т.е. обычный текст и размеченный, и, может быть, узнаете что-то новое о процессе разметки.

Как правило, это замедляет процесс включения документации в систему так как предоставленный вами текст должен быть предварительно размечен. Это может занять от нескольких часов до нескольких дней, но она будет включена.

== Хотите знать больше о SGML и DocBook?

Для начала прочтите link:{fdp-primer}[*Documentation Project Primer*]. Этот документ является подробным описанием всего, что вам нужно знать для работы с документации FreeBSD. Это большой документ, разделенный на много меньших файлов. Вы можете также просматривать его в виде link:{fdp-primer}#book[*одной большой страницы*].

http://www.oasis-open.org/cover/sgml-xml.html[*http://www.oasis-open.org/cover/sgml-xml.html*]::
Страница SGML/XML. Содержит бесчисленное множество ссылок на информацию о SGML.
http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html[*http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html*]::
"Gentle Introduction to SGML". Рекомендуемое чтение для всех, кто хочет изучить SGML более подробно с уровня начинающего.
http://www.oasis-open.org/docbook/[*http://www.oasis-open.org/docbook/*]::
DocBook DTD поддерживается OASIS. Эти страницы предназначены для пользователей, которые чувствуют себя уверенно с SGML и хотят изучить DocBook.

link:..[FreeBSD Documentation Project Home]
